[BETA] Make advanced price calculations

This endpoint is currently in beta. Errors may happen. Changes may occur. Calculate total and component-based costs for a specified period using systematic tariff price calculation with hybrid input structure.

This endpoint supports all component types (KWH, DEMAND, CAPACITY, REACTIVE, EXCESS, FIXED, TAX) with flexible input formats, comprehensive TOU handling, and systematic price calculation.

Systematic Price Calculation:

• Forward-looking approach: Finds ALL applicable tariff prices for each component
• Multiple price versions: Each tariff price becomes a separate price_version in the response
• Component price calculation: Component ‘price’ is the sum of all its price_versions’ calculated_price
• Geographic and temporal filtering: Automatically filters prices by location and validity periods
• TOU-aware pricing: Handles Time-of-Use pricing systematically without backward lookups

Component Type Filtering:

• component_types parameter: Optional array to specify which component types to include in calculations and responses
• Available types: KWH, FIXED, CAPACITY, DEMAND, REACTIVE, EXCESS, TAX
• Default behavior: If not specified or empty, all component types are included
• Response control: Filters both calculated components and automatic components (e.g., FIXED fees that don’t require input)
• Use cases:
  • Exclude specific component types from calculations (e.g., only calculate KWH and DEMAND components)
  • Prevent automatic inclusion of FIXED components when not desired in response
  • Focus calculations on specific component categories for targeted analysis

Hybrid Input Structure:

• Input Format: Array of input objects with ‘id’, ‘value’, ‘unit’, ‘tou’ fields
• Component Mapping: Input IDs directly target specific tariff components
• Systematic Processing: Each input creates one or more price_versions based on applicable tariff prices
• Component Identification: Get input IDs from /tariffs// endpoint
• Automatic Components: Some components (like FIXED fees) may be included automatically even without explicit input

Time-of-Use (TOU) Support:

• Systematic TOU handling: TOU inputs are processed as separate components
• Individual TOU entries: Use separate input objects with ‘tou’ field for each TOU level
• Component-specific TOU: Each TOU-enabled component can have its own TOU requirements
• TOU identifier examples: {"id": "Test_ON_PEAK", "value": 50.0, "tou": "ON_PEAK"}
• Flexible TOU usage: Non-TOU tariffs work without any TOU specification
• Standard TOU types: ‘ON_PEAK’, ‘OFF_PEAK’, ‘CRITICAL_PEAK’, ‘PARTIAL_PEAK’, ‘SUPER_ON_PEAK’, ‘SUPER_OFF_PEAK’
• TOU level IDs: Use specific TOU level IDs (e.g., ‘tou_123’) for precise targeting
• Separate results: Each TOU input creates its own result entry in the response

Enhanced Response Structure:

• Component results: Each input creates a separate result entry with detailed price_versions
• Price versions array: Shows all applicable tariff prices that contributed to the component price
• Systematic pricing: Component ‘price’ = sum of all price_versions’ calculated_price
• Geographic validity: Only includes prices valid for the specified location
• Temporal validity: Only includes prices valid during the calculation period

Supported Components:

• KWH: Energy consumption (numbers, time-series arrays)
• DEMAND: Peak demand (numbers) - supports TOU pricing
• CAPACITY: Contracted capacity (numbers) - supports TOU pricing
• REACTIVE: Reactive power (numbers) - supports TOU pricing and unit specification
• EXCESS: Excess consumption penalties (numbers only)
• FIXED: Fixed fees (optional values for quantity-based fixed fees, or pure flat fees)
  • Automatic inclusion: FIXED components may be included automatically without explicit input
  • Control via component_types: Use component_types parameter to exclude if not desired
• TAX: Tax components (numbers only)
• Direct Component Targeting: Use prezio_code from tariff retrieve endpoint
• Alternative ID Format: Use com_id format (e.g., ‘com_123’) for specific targeting

FIXED Component Handling:

• Automatic calculation: FIXED components are calculated automatically based on period duration
• No input required: FIXED components don’t require input values in the inputs object
• Prorate parameter: Controls how FIXED components are calculated:
  • prorate=false (default): Charges for whole periods that fall within the requested timeframe
  • prorate=true: Calculates proportional cost based on actual period duration
• Period-based calculation: Uses component.period_unit or falls back to tariff.billing_period
• Component type filtering: Respects component_types parameter - excluded if FIXED not in component_types

Use Cases:

• Multi-component tariff calculations with systematic price discovery
• Commercial/industrial demand charge calculations with TOU pricing
• Geographic price variations with automatic location-based filtering
• Temporal price changes with automatic period-based filtering
• Mixed consumption and demand pricing with detailed price version tracking
• Capacity planning and reactive power cost calculation
• Control over automatic component inclusion (e.g., excluding FIXED fees when not relevant)
• Focused analysis on specific component categories with systematic pricing